Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d21 / pc_ipc.arc / PC-IPC.DOC < prev next >

Wrap

Text File | 1989-12-03 | 76.9 KB | 1,757 lines

IPC USER'S MANUAL Inter-Process Communication for DOS DONNELLY SOFTWARE ENGINEERING 5082 WENDOVER RD. YORBA LINDA, CA 92686 (714) 970-9612 Table of Contents INTRODUCTION...........................1 IPCINST.COM..........................1 PC-IPC.COM...........................1 IPCLIB.LIB...........................1 PC-IPC.H.............................1 PC-IPC.DOC...........................1 TX_PROC.C and RX_PROC.C..............1 IPCSAMP.ASM..........................1 SYSTEM REQUIREMENTS....................1 INSTALLATION...........................2 USAGE..................................3 Using IPCINST.COM....................3 Using PC-IPC.COM.....................5 PC-IPC Commands....................5 PC-IPC Parameters..................7 PC-IPC EXAMPLES........................9 Command Line Example.................9 Batch Mode Example..................11 Batch Mode Within DESQview..........12 CREATING IPC APPLICATIONS.............14 Overview............................14 IPC Commands........................16 IPC Status..........................19 C Bindings for IPCLIB.LIB...........21 Creating main().....................22 Compiling and Linking...............24 Running TX_PROC and RX_PROC.........25 Assembly Interface..................26 ERROR MESSAGES........................27 PC-IPC Error Messages...............27 PC-IPC Return Status................28 IPCLIB Error Messages...............29 PURCHASE INFORMATION..................31 ACKNOWLEDGMENTS.......................33 INDEX.................................34 Examples, Figures, and Tables Example 1 - PC-IPC Command Line Example........................9 Example 2 - PC-IPC Batch Mode Example.........................11 Example 3 - PC-IPC Batch Mode Within DESQview.................12 Figure 1 - Sample AUTOEXEC.BAT file............................2 Figure 2 - Two Representations of an IPC_PARAM_BLOCK..........14 Figure 3 - Bit-fields of 'status' in IPC_PARAM_BLOCK..........19 Table 1 - Required Values of 'my_id' for IPC Commands.........18 Table 2 - Inputs, Outputs, and Status for IPC commands........20 Table 3 - Status Values Returned in ERRORLEVEL................28 IPC User's Manual IPC 1.0 1 INTRODUCTION This set of programs provides the capability of Inter-Process Communication for applications running under the MS-DOS operating system. It can, for example, be used to pass information between separate processes running within DESQview windows, or between batch jobs, or your own applications. The set is comprised of 8 files: IPCINST.COM is the heart of Inter-Process Communication. It is a Terminate and Stay Resident (TSR) program that serves as a "Post Office" for the messages and data exchanged between processes. A process may deposit information into IPC or retrieve information from it. The information sent to IPC is maintained in memory until a request is made for it. More than one instance of IPC can be resident in memory at any time (several Post Offices). IPC can be configured to hold from 1 to 52 kilobytes of information (Post Office capacity). Any number of messages of any size can be stored by IPC within the 52-K memory limit (pieces of mail). PC-IPC.COM provides the capability to pass information from one program to another through DOS's command-line interface. Two methods are provided to accomplish this. The first method is an interactive mode where messages are sent and received on the command line. The second method is designed for batch mode where PC-IPC commands and data are contained in batch files and the DOS environment table. IPCLIB.LIB is a linkable library of functions that provide an interface to IPC. Programmers can therefore write their own "C" applications to take advantage of IPC's capabilities. Included in the library are the IPC interface call, an error handler, an initialization routine, a routine to test for IPC's presence, and a version identification routine. PC-IPC.H is the "C" include file for use by application programmers. It contains definitions for status codes, commands, error codes, and the data structure used for communicating with IPC. PC-IPC.DOC is this documentation file. TX_PROC.C and RX_PROC.C are sample C programs that illustrate how to use IPCLIB in developing your own applications. IPCSAMP.ASM is a sample program that demonstrates direct access to IPC through assembly language. SYSTEM REQUIREMENTS A PC, XT, AT, or 386 compatible with a minimum of 256K, at least one floppy disk drive, MDA, HGC, CGA, EGA, or VGA display, DOS 2.0 or later (3.0 or later recommended) are required. IPC User's Manual IPC 1.0 2 INSTALLATION This section describes how to install and set up IPC on your disk and in your computer's memory. After de-archiving the files IPCINST.COM, PC-IPC.COM, PC-IPC.H, PC- IPC.LIB, PC-IPC.DOC, TX_PROC.C, RX_PROC.C and IPCSAMP.ASM, you may want to place them in a subdirectory on your hard disk. If you intend to use IPCINST.COM and PC-IPC.COM often, they should be placed in a directory that is in the DOS path (see SET or PATH in your DOS User's Manual). If you want IPC to be resident in memory when you turn on your computer, add "IPCINST.COM /V=xx /A=zz" to the file AUTOEXEC.BAT in your top-level directory. Figure 1 illustrates a sample AUTOEXEC.BAT file. See the "USAGE" section below for an explanation of the command parameters /V and /A. ______________________________________________________________________ ECHO OFF PATH C:\DOS;C:\;C:\TURBOC;C:\IPC IPCINST.COM /V=62 /A=3 DATE TIME ECHO ON Figure 1 - Sample AUTOEXEC.BAT file. The PATH command points to, among others, a subdirectory on drive C: called IPC. Assuming that all IPC files are in C:\IPC, DOS will be able to run them regardless of what the default drive or directory is. ______________________________________________________________________ If you would rather not have IPC resident in memory all the time, you can install it whenever you like. This can be done either at the command line or within a Batch file. The format of the command is the same as when used in AUTOEXEC.BAT. Please note that because IPC is a TSR, once it is installed, it remains in memory until the computer is restarted. IPC can be used in conjunction with DESQview, the multi-tasking operating system. IPCINST.COM must be run prior to starting DESQview. Otherwise, IPC is "hidden" within a DESQview window and cannot be accessed by programs (such as PC-IPC.COM) running in other windows. You may add the line "IPCINST.COM /V=xx /A=zz" to the batch file DV.BAT before the line "DV %1 %2 %3 %4 %5". Or you can install IPC at the command line prior to starting DESQview. For example, C>ipcinst /v=60 /a=4 C>dv IPC User's Manual IPC 1.0 3 USAGE This section describes the usage of and the various parameters for IPCINST.COM and PC-IPC.COM. Using IPCINST.COM : IPCINST /V=xx /A=zz /V=xx (an optional parameter) The memory-resident program IPCINST.COM requires an interrupt vector from the Interrupt Vector Table (IVT) which occupies the first 1024 bytes of your computer's memory. You can specify which one of the 256 vectors (addresses) IPC should use. You cannot pick just any vector since many are used by DOS, ROM-BIOS, EMS memory, the 80x86 processor, hardware interrupts, other TSRs, etc. Although many vectors are standard, every computer manufacturer, add-on board manufacturer, software package, and especially TSRs, may use any of the vectors in the IVT. This makes your hardware / software configuration unique. Therefore IPC makes no demands that a particular vector be available. The "/V=xx" parameter allows you to tell IPC which vector to use. "xx" is the vector number, in hexidecimal (hexidecimal sequence: 0, 1, 2 ... 8, 9, A, B ... E, F, 10, 11 ... 19, 1A ... 1F, 20 ...) in the range 00 through FF. For a "standard" PC, vectors 4B through 66 inclusive and 78 through FF inclusive are generally available. By default, IPCINST.COM uses vector 60 (i.e. /V=60). If you omit this optional parameter and do not receive an error, vector 60 is used by IPC. IPCINST.COM will not install if the specified vector is already in use. You can install as many IPC "Post Offices" as will fit in memory and in the Interrupt Vector Table. Each vector that IPC uses represents another "Post Office". Each instance of IPC is independent of any others. In other words, IPCs do not communicate with each other. Which IPC instance a program communicates with is determined by PC-IPC.COM (and IPCLIB.LIB). The following establishes 3 instances of IPC in memory: C>ipcinst /v=61 C>ipcinst /v=6E C>ipcinst Note that the /V parameter is not specified in the last command. This last instance of IPC uses the default vector 60 (hex). The first and second instances use vectors 61 and 6E, respectively. /A=zz (an optional parameter) Normally, IPC reserves 1024 bytes (1K) of memory to store messages. This may be increased (up to 52K) by using the /A parameter when installing IPC in memory. "zz" can be any number between 1 and 52 (decimal). In addition to the memory reserved for messages, space is IPC User's Manual IPC 1.0 4 needed by IPC's code: approximately 12K. The least amount of memory each instance of IPC uses is 13K, and at most 64K. If, for example, you run the following batch file: echo off echo Installing IPC ipcinst /v=7D /a=40 ipcinst /a=15 ipcinst /v=D9 echo IPC installed at vectors 7D, 60, and D9 echo on the first IPC instance uses 52K, the second 27K, and the last 13K, for a total of 92K. The amount of memory set aside for messages in this example is enough to contain almost 18 pages of single-spaced, 1-inch margined text. Assuming that the total memory on your system is 512K, and that DOS and COMMAND.COM occupy 50K, and that no other memory resident programs are loaded, you would have about 370K left for running programs. Remember that memory reserved by IPC is no longer available to run other programs until the computer is restarted. IPC User's Manual IPC 1.0 5 Using PC-IPC.COM : PC-IPC parameter(s) command Parameters and commands must be separated by spaces. Only one IPC command may appear on the command line. If more than one command is present, the last is taken used and the others are ignored. With one exception, commands and parameters may appear anywhere on the command line (see /S, below). PC-IPC Commands There are 12 commands that PC-IPC can use for communicating with the memory resident IPC. Six of these deal with transmitting data to and from IPC. Two provide information about IPC. Two control IPC's ability to send and receive messages. The last two provide a method of routing the messages with identification tags. IPC Communication /S=data /S=(id)data The /S commands allow you to send data to IPC. The data may be any valid ASCII characters. Whitespace characters (space, tab) are compressed to a single space. If multiple spaces or tabs are desired, enclose the entire command in double quotes. For example, C>pc-ipc "/S=Now is the time" preserves the spacing as it appears on the command line. If the double quotes are not present, multiple spaces between words are compressed to one space. All characters on the command line that appear after the /S commands are taken as data. Therefore, the /S commands should appear last on the command line. The (id) command qualifier "addresses" the data to a particular process (see /G and /I, below). Note that the parentheses are required but are not included with the data saved by IPC. Therefore, C>pc-ipc /S=(7)Hello process #7, I'm ready for data! sends "Hello process #7, I'm ready for data!" to Process-7. If no process id is specified, the default is 0 ( /S=(0)data is equivalent to /S=data ). All messages sent to IPC by PC-IPC are "NULL terminated strings." A NULL character has the ASCII value of zero and is used by C (and other languages) to signal the end of a character string. PC-IPC automatically appends a NULL to every message it sends to IPC. So if the message is "/s=123456789", IPC actually receives ten ASCII characters: "49 50 51 52 53 54 55 56 57 00" (decimal). In addition to the NULL character that PC-IPC appends to each message, IPC requires 22 bytes of overhead for each message it stores. These 22 bytes are used by IPC to keep track of the message's location, the sender's and recipient's process ids, and the size of the message. IPC User's Manual IPC 1.0 6 Using the previous example, 32 bytes (9 characters + 1 NULL + 22 overhead bytes) of message space are required to store the message. /R /R=file /W /W=file The /R and /W commands allow you to retrieve data from IPC. The /R command requests it immediately. The data is displayed on the standard output. The /R=file command is similar to /R except the data is written to disk. The specified file may be any valid pathname (e.g. /R=A:\IPCDATA\PROC1.DAT). If the file already exists, the requested data is appended to the end of the file. For both /R and /R=file, if IPC has no data the message "(No Data Available)" is written to the standard output. The /W commands are similar to the /R commands except that if no data is available at the time the request is made, PC-IPC will wait until data is available for the process making the request (see /I, below). This command should only be used when PC-IPC is running in a multi- processing environment. A message can only be retrieved once from IPC. When a message is retrieved, it is erased from IPC's list. IPC Information /H The /H (help) command displays a brief description of the valid parameters and commands PC-IPC.COM recognizes. /Q The /Q (query) command checks to see if IPC is resident in memory, determines the number of messages available for the requesting process, and calculates the amount of free message space. For example, assume that Process-2 sends one message, Process-3 sends three messages, and Process-5 sends one message all addressed to Process-4. When Process-4 issues the command "pc-ipc /i=4 /q", the following status message appears on the display, "5 Messages Available. 743 Bytes Free Space. IPC is Installed, Enabled". IPC Control /D IPC can be disabled so that it will no longer respond to Communication commands (/R, /W, /S). While disabled IPC still responds to any information requests (/Q and /H). Turning IPC off is not the same as removing it from memory (only rebooting the system can do that). The process id that disables IPC is the only one that can enable it again. The process id that disables IPC must be "recognized" by IPC (see /G). /E IPC User's Manual IPC 1.0 7 The /E command, when issued by the same process id that issued the /D command, reenables IPC to accept Communication commands. IPC Routing /G /G=n If a process requires a unique handle or id for either sending or receiving messages, it can use the /G command to obtain one (or more). IPC maintains a list of 10 process ids (numbered 0 through 9). When a process requests an id with the /G command, IPC marks that id as "in use" and will not reissue that id until it has been relinquished (using /G=n). A process id obtained using /G is said to be "recognized" by IPC. A "valid" id is a number between 0 and 9 that may not necessarily have been obtained using /G. Except for /D and /G=n, IPC responds to any command from a valid process id. Therefore, it is not necessary to use the /G command to send or receive messages. Typically, the /G command would be the first command a process would send to IPC. When the process is about to finish, or no longer needs the id, the /G=n command relinquishes the id "n", making it available for other processes. Until specifically relinquished, the id remains "in use", even if the process terminates. PC-IPC Parameters /B /B=setvar The /B parameter tells PC-IPC that it is running in batch mode. All output that PC-IPC normally sends to the display is instead placed in the process's environment table and in COMMAND.COM's environment table (see the SET command in the MS-DOS User's Manual). This is useful in batch processes for obtaining, for instance, a process id. If a variable name (setvar) is not specified, PC-IPC creates one with the following format: IPCvvi=data, where "IPC" is constant, "vv" is the vector number of IPC, "i" is the process id, and "data" is the data requested by Process-i. The /B=setvar parameter allows the process to specify the variable name to use. The variable name must be less than 9 characters in length. For versions of DOS lower than 3.0, the /B parameter is of limited usefulness because the environment size is limited to 160 bytes. For versions 3.0 and later, the environment size can be set in the CONFIG.SYS file by including the line "SHELL=C:\COMMAND.COM /P /E:nnnnn". The "/P" parameter makes COMMAND.COM remain in memory and forces execution of AUTOEXEC.BAT. The "/E:nnnnn" parameter specifies the size of the environment. For DOS versions between 3.00 and 3.10 "nnnnn" is the environment size in 16-byte paragraphs: range 10 - 62 (160 to 992 bytes). For DOS versions 3.20 and greater, "nnnnn" is the environment size in bytes: range 160 - 16384. IPC User's Manual IPC 1.0 8 /I=n The /I parameter allows a process to identify itself to IPC. If this parameter is not specified, 0 is the default (i.e. /I=0). "n" must be a "valid" id (0 through 9). "n" does not need be obtained by the currently running process. For example, if you type "pc-ipc /g" on the command line, PC-IPC displays "1". Technically speaking, you just ran a process (a DOS process). If you then run another DOS process by entering "pc-ipc /i=1 /s=Howdy Doody", IPC accepts and stores the message. IPC is not "aware" that two separate DOS processes were involved. /V=xx The /V parameter is equivalent to the /V parameter for IPCINST.COM. It specifies the vector (Post Office) to use when calling IPC. The default, as with IPCINST.COM, is 60 (hex). IPC User's Manual IPC 1.0 9 PC-IPC EXAMPLES This section presents examples of the command line interface to IPC: PC-IPC.COM. EXAMPLE 1 : This example shows how to install IPC and use PC-IPC to send and receive data. The commands to be entered are shown at the "A>" prompt. The program's response is shown below the command. A descriptive comment is shown to the right of the command. A>IPCINST /V=60 /A=3 Install IPC at vector 60H reserving 3K for messages IPC-INSTALL 1.0 Copyright (c) 1989, Donnelly Software Engineering. IPC Installed at vector 60h. 3072 bytes available for messages (52902 maximum). A>PC-IPC /Q Check to see that IPC is installed and ready for messages 0 Messages Available. 3072 Bytes Free Space. IPC is Installed, Enabled. A>PC-IPC /S=Abraham Lincoln Send a message from Process-0 to Process-0 (the default process-id) A>PC-IPC /R Retrieve the message just sent Abraham Lincoln A>PC-IPC /G Get a process-id from IPC 1 Send messages to Process-1 A>PC-IPC /S=(1)Four score and 7 years ago A>PC-IPC "/S=(1)our fathers brought forth on this continent" A>PC-IPC /S=(1)a new nation, conceived in liberty, A>PC-IPC /R Get a message for Process-0 (No Data Available) A>PC-IPC /I=1 /Q Check for Process-1 messages 3 Messages Available. 2890 Bytes Free Space. IPC is Installed, Enabled. A>PC-IPC /I=1 /R=LINCOLN.TXT Get a message and put it in a file LINCOLN.TXT (In file LINCOLN.TXT) IPC User's Manual IPC 1.0 10 A>TYPE LINCOLN.TXT Type the file Four score and 7 years ago Send a message from Process-1 to Process-0 A>PC-IPC /I=1 /S=(0)and dedicated to the proposition, A>PC-IPC /I=1 /R Get the next message for Process-1 (note the effect of the quotes on the spacing) our fathers brought forth on this continent A>PC-IPC /R Get the next message for Process-0 and dedicated to the proposition, A>PC-IPC /I=1 /R Get the next message (note the effect on spacing with no quotes) a new nation, conceived in liberty, A>PC-IPC /G=1 Give up id-1 IPC User's Manual IPC 1.0 11 This section presents examples of the batch mode interface to IPC. EXAMPLE 2 : This example illustrates the use of PC-IPC in a batch file. First, a request is made for a unique ID which is saved in the environment table as "myid". Then a request is made to determine if any messages are available. While there are messages available, the program writes the message to a file and loops to get another. When there are no more messages, the data file is displayed, the environment variables are deleted and the process ends. You may want to use a text editor to cut this example from this .DOC file and paste it into a .BAT file. echo off REM This batch file assumes that IPC is already installed and that REM one or more messages have already been sent to IPC for the REM process id that will be returned from the /g command. To REM do this, enter the following at the command line: REM REM A>ipcinst REM A>pc-ipc /s=(1)Goldy Locks REM A>pc-ipc /s=(1), Papa Bear REM A>pc-ipc /s=(1), Mama Bear REM A>pc-ipc /s=(1)and Baby Bear REM REM Get an ID from IPC and put it in the environment. pc-ipc /b=myid /g :AGAIN REM Use that ID to get a count of available messages. pc-ipc /b=procdata /i=%myid% /q REM Test to see if any messages are available. if %procdata%==0 goto DONE REM Use the ID to write the message to a file. pc-ipc /i=%myid% /r=mydata%myid%.txt REM Loop until there are no more messages. goto AGAIN :DONE REM Type the file containing the messages. echo Typing mydata%myid%.txt... type mydata%myid%.txt REM Clean up before leaving. REM Relinquish ID. pc-ipc /g=%myid% REM Conserve environment space. set procdata= set myid= echo on exit IPC User's Manual IPC 1.0 12 This section illustrates the use of PC-IPC within 2 DESQview windows. EXAMPLE 3 : The two batch files each run within separate "DOS (128K)" windows. The first batch file continuously sends messages to IPC until IPC's message space is full and then terminates. The second batch file continuously retrieves messages from IPC. When no more messages are available, it terminates. In order to run this example, first make certain that IPC is installed (run IPCINST.COM) prior to starting DESQview. Next, open two "DOS (128K)" windows. Arrange the windows so that they are both visible. In the first window start the batch file FILLIPC.BAT. It begins sending messages to IPC. Switch to the second window and start MTIPC.BAT. It begins retrieving messages from IPC. Depending upon which window is the "foreground process," and the ratio of "foreground ticks" to "background ticks", the number of available messages increases or decreases. Try switching between windows to see the effect on available messages. ECHO OFF REM FILE : FILLIPC.BAT ECHO FILLING IPC TO CAPACITY... REM Note the use of IF ERRORLEVEL... for status checking. REM (See "PC-IPC Return Status" section) REM Check that IPC is installed PC-IPC /Q IF ERRORLEVEL 12 GOTO DONE :LOOP PC-IPC /S=Tish! I love it when you speak French! -- Gomez Addams REM Quit if IPC is full IF ERRORLEVEL 11 GOTO DONE REM Display message count, available memory PC-IPC /Q GOTO LOOP :DONE ECHO ON ECHO OFF REM FILE : MTIPC.BAT ECHO EMPTYING IPC... REM Check that IPC is installed PC-IPC /Q IF ERRORLEVEL 12 GOTO DONE :LOOP REM Put the message in environment variable MSG PC-IPC /B=MSG /Q ECHO %MSG% IF %MSG%==0 GOTO DONE PC-IPC /R GOTO LOOP :DONE ECHO ON IPC User's Manual IPC 1.0 13 Another experiment that can be performed within DESQview is to disable IPC. Start FILLIPC.BAT in one window. While it is running, switch to the other window and type "pc-ipc /d". This disables IPC message processing. FILLIPC continues to run because no check is performed within the loop for a "disabled" status. To resume sending data, type "pc-ipc /e" in the second window. IPC User's Manual IPC 1.0 14 CREATING IPC APPLICATIONS This section discusses the design and implementation of your own applications using IPC. It is assumed here that you are familiar with the C programming language, and have access to a C compiler and a linker. Overview The object library IPCLIB.LIB is supplied with this product to enable you to write your own applications that take advantage of IPC's abilities. But before a detailed discussion of the mechanics of code writing, this is how IPC works from an application's point of view. IPC is a TSR that is called through an interrupt vector assigned when it is loaded into memory. All information passed to and from IPC uses a data structure known as an IPC_PARAM_BLOCK (Figure 2). The IPC_PARAM_BLOCK contains the command IPC is to perform, the data it is to process and its size, the sending-process id, the receiving-process id, and status and error codes. ______________________________________________________________________ 0 15 31 struct IPC_PARAM_BLOCK +---------------------------------+ { | my_id | to_id | unsigned int my_id; +---------------------------------+ unsigned int to_id; | command | status | unsigned int command; +---------------------------------+ unsigned int error; | error | size | unsigned int status; +---------------------------------+ unsigned int size; | data_ptr | void far *data_ptr; +---------------------------------+ }; a) b) Figure 2 - Two Representations of an IPC_PARAM_BLOCK. a) The first six fields are each 16 bits wide, the data pointer is 32 bits wide. b) This is the C structure similar to that found in the include file PC-IPC.H. ______________________________________________________________________ When an application sends a message to IPC, the data is copied to memory that is within IPC's control. Once the data has been copied, the application may modify or delete its own data. In fact, the application can terminate (freeing its memory), without affecting IPC's copy. IPC dynamically allocates enough memory for each message sent. The only data "too big" to fit inside IPC is that which exceeds the limit set by the /A parameter when IPC was installed. Retrieving data from IPC is the inverse of sending data. The application supplies a destination for the data (in the 'data_ptr' field). IPC copies the the first message in its list for that process (identified by the 'my_id' field), and fills the 'size' field with the IPC User's Manual IPC 1.0 15 number of bytes copied. Subsequent requests for data by the same 'my_id' will retrieve the next available message in IPC's list. Each message is copied to the memory location specified in 'data_ptr' and then deleted from IPC's list. You must make certain that the buffer to which IPC copies the data is large enough to hold the largest anticipated message. Otherwise, IPC may overwrite your application's code or data. In the case where no data is available for 'my_id', IPC sets the 'size' field to zero and clears the 'avdata' flag in the 'status' field (see the "IPC Status" section). IPC User's Manual IPC 1.0 16 IPC Commands The following commands are defined in PC-IPC.H and are recognized as valid entries for the 'command' field: IPC_CMND_INQUIRE Inquire of IPC its current state. The 'status' field is set to indicate whether IPC is installed, enabled, in error, and if data is available. If any messages are available for the process id specified in 'my_id', the number of messages is returned in 'size' and the 'avdata' flag in 'status' is set. If 'data_ptr' contains a valid pointer (i.e. is not zero), an unsigned integer representing the amount of free message space (in bytes) is written to the location specified in 'data_ptr'. You may want to use a union to retrieve the amount of free memory. If you send a far pointer to a character array in 'data_ptr', you may have difficulty using the unsigned integer that IPC returns. If, for example, you define the following union variable, union { char str_data[256]; int int_data; } data_block; you can then initialize 'data_ptr' with either of the following statements: init_param_block(param_ptr, my_id, to_id, IPC_CMND_INQUIRE, 0, data_block.str_data); or, init_param_block(param_ptr, my_id, to_id, IPC_CMND_INQUIRE, 0, &data_block.int_data); In either case you have access to whichever type of data IPC returns. If you use the first example prior to calling IPC, IPC returns an unsigned int to the location in 'data_ptr'. Your application can access the data as follows: printf("%u Messages Available. %u Bytes Free Space.\n", param_ptr->size, data_block.int_data); IPC_CMND_ENABLE IPC compares the value contained in 'my_id' with the process id that disabled IPC. If the values are the same, IPC is again available to receive and send data. Otherwise, the 'error' flag in 'status' is set and 'error' contains the value of the error. IPC_CMND_DISABLE Any process with a recognized 'my_id' (one obtained using the IPC_CMND_REQID command) may disable IPC. While disabled, the only commands IPC will respond to are IPC_CMND_INSTALL, IPC_CMND_VERS, IPC_CMND_INQUIRE, and IPC_CMND_ENABLE. IPC User's Manual IPC 1.0 17 IPC_CMND_INSTALL IPC can be reset using this command. Resetting IPC deletes all messages in IPC's list, and sets the internal status flag to the normal condition (installed, enabled, no data, no error). The value of 'my_id' must be zero. When you first install IPC using IPCINST.COM, it calls itself with this command to verify that the installation went properly. IPC_CMND_RDATA Use this command to retrieve data from IPC. IPC returns the first available message in its list that corresponds to the value sent in 'my_id'. IPC then copies the message to the location specified in 'data_ptr'. In order for your application to determine the id of the process that sent the message, the sending process' id is returned in 'to_id'. The size of the message, in bytes, is returned in 'size'. The 'avdata' flag in 'status' is set. The message is deleted from IPC's list. If no message is available for 'my_id', 'avdata' is cleared, and 'size' is set to zero. IPC_CMND_RDATAW The only difference between this command and IPC_CMND_RDATA is that IPC will only return if there is a message available in its list for the process specified in 'my_id'. IPC will put your application "on hold" until a message is available. This command should only be used in a multi-process environment (such as DESQview). IPC_CMND_SDATA This command copies the data located by the far pointer 'data_ptr' to an internal message list for the number of bytes specified in 'size'. It also saves 'my_id' and 'to_id' and associates them with the message. This requires 22 bytes of overhead for each message IPC stores. Therefore, each message uses 'size' + 22 bytes of IPC message space. IPC_CMND_REQID Your application can obtain one or more (9 total) unique ids from IPC that can be used for message routing. The new id is returned in 'my_id'. Also, if there are any messages already available for the newly allocated id, the 'avdata' flag is set in 'status'. To IPC, there are two types of process ids. There are "valid" process ids and there are "recognized" process ids. A valid process id is any number between 0 and 9, inclusive. A recognized process id is one that is currently marked "in use", or allocated, by IPC. Many commands require that the value sent in 'my_id' be one of these types. Table 1 summarizes these requirements. Notice that only a valid id is needed to Read Data or Send Data. Therefore, a process may assume, or take on, the id of another process. Or, your application may "hard-wire" process ids into the code. IPC User's Manual IPC 1.0 18 ______________________________________________________________________ Command my_id --------------- ----------- Inquire Valid Enable Disable Id Disable Recognized Install 0 Read Data Valid Read Data Wait Valid Send Data Valid Request ID Don't Care Delete ID Recognized Version Don't Care Table 1 - Required Values of 'my_id' for IPC Commands. ______________________________________________________________________ IPC_CMND_DELID A process id can be returned to IPC's pool of available ids using this command. The value contained in 'my_id' must be the same as an id that is marked by IPC as "in-use." Process ids need not be returned in the same order they were assigned. IPC_CMND_VERS This command copies a character string, that represents the current version of IPC, to the location specified in 'data_ptr'. The length of the string is returned in 'size'. IPC User's Manual IPC 1.0 19 IPC Status IPC returns the status of each operation in the 'status' field of the IPC_PARAM_BLOCK. By performing bit-wise comparisons on 'status' information about IPC can be determined. The bit-fields of 'status' are shown in Figure 3. If the error bit is set, the error code is returned in the 'error' field of the IPC_PARAM_BLOCK. Otherwise, 'error' is zero. ______________________________________________________________________ 15 0 +---------------------------------------------------------------+ | | | | | | | | | | | | A | R | I | E | | +---------------------------------------------------------------+ Figure 3 - Bit-fields of 'status' in IPC_PARAM_BLOCK. Blank fields are unused. E : if set, IPC is enabled. I : if set, IPC is installed. R : if set, an error occurred, error code is returned in 'error' field of IPC_PARAM_BLOCK. A : if set, one or more messages are available in IPC's list for the process id specified in 'my_id'. ______________________________________________________________________ Defines are provided in PC-IPC.H for performing the bit-wise comparisons. For instance, to determine if an error resulted from the last call to IPC, your application can do either of the following: if (param.status & IPC_STAT_ERROR) ipc_error(param.error); or, if (param.error) ipc_error(param.error); The required input fields, required output fields, and status returns are summarized in Table 2. IPC User's Manual IPC 1.0 20 ______________________________________________________________________ STATUS (1) ERROR COMMAND INPUT OUTPUT I E A R VALUE -------------- ---------------- ---------- ------- ----- Inquire (2) my_id, data_ptr size, data_ptr x x x x x Enable my_id (3) x x x x Disable my_id (4) x x x x Install my_id (5) x x x x Read Data my_id, data_ptr data_ptr, size, x x x x x to_id (6) Read Data Wait my_id, data_ptr data_ptr, size, x x x x x to_id (6) Send Data my_id, to_id, size (7) x x x x data_ptr, size Request ID my_id my_id x x x x x Delete ID my_id (4) x x x x Version data_ptr data_ptr, size x x Table 2 - Inputs, Outputs, and Status for IPC commands. "x" indicates where IPC may set the flag or value. (1) Status Flags I:Installed, E:Enabled, A:Available Data, R:Error. (2) The number of available messages for process 'my_id' is returned in 'size'. If 'data_ptr' contains a valid destination address (i.e. not zero), the size of free message space (in bytes) is returned through 'data_ptr'. (3) 'my_id' must match that used in Disable. (4) Must be a recognized process id (i.e. one that is currently allocated). (5) Must be process id zero (0). (6) 'to_id' contains the message sender's id. (7) If Send Data is unsuccessful due to insufficient memory, the amount of available message space is returned in 'size'. ______________________________________________________________________ IPC User's Manual IPC 1.0 21 C Bindings for IPCLIB.LIB void far pc_ipc(unsigned int vector, IPC_PARAM_BLOCK far *param_ptr) This is the interface to the memory-resident portion of IPC. The two parameters are the vector number for IPC's interrupt, and a far pointer to the parameter block. Note that 'param_ptr' is a far (32- bit) pointer. If your compiler does not support far pointers, you need to devise a method of creating them in order to use the functions in IPCLIB.LIB. void far ipc_error(unsigned int index) This is the error handler for any errors returned by IPC. If 'status' logically ANDed with IPC_STAT_ERROR is true, then a call to ipc_error with 'index' set to the value in the 'error' field of the IPC_PARAM_BLOCK will write a descriptive message to the standard output. Another method of error detection is to check if 'error' is non-zero. ipc_error is a "fatal" routine in that it terminates the process (your application). 'index' is returned to the parent process. If the parent process is a batch file running under DOS, then ERRORLEVEL can be used to determine the success of your application. void far init_param_block(IPC_PARAM_BLOCK far *param, unsigned int my_id, unsigned int to_id, unsigned int command, unsigned int size, void far *data_ptr) This routine initializes the data structure used for passing information to and from the memory-resident program IPC. 'param' is a far pointer to a variable of the type IPC_PARAM_BLOCK. 'data_ptr' is a far pointer to the data source or destination depending on the command used. The other parameters are unsigned integers. All parameters to init_param_block are required. Any fields in the IPC_PARAM_BLOCK that are not required for a particular command should be initialized to zero (or 0L for data_ptr). int far pc_ipc_installed(unsigned int vector) This routine determines if, indeed, the memory-resident program IPC is present at the specified vector. It returns true if IPC is installed, otherwise it returns false. Typically, this function call is made in an application's start-up, or initialization, routine. void far get_ipc_version(unsigned int vector, char far *version) Places a string that represents the version of IPC into the memory location pointed to by 'version'. IPC User's Manual IPC 1.0 22 Creating main() Your application should contain 5 things in order to use the resident portion of IPC: 1) the "#include pc-ipc.h" directive for the command, error, and status defines, the IPC_PARAM_BLOCK type definition, and the function prototypes 2) a variable declaration of the type IPC_PARAM_BLOCK (or a pointer to a malloc'ed chunk of memory) 3) a call to pc_ipc_installed to verify IPC's presence 4) a call to init_param_block to initialize the IPC_PARAM_BLOCK with a command and parameters 5) a call to pc_ipc Refer to the sample files TX_PROC.C and RX_PROC.C, distributed with this product, for the following discussion. For convenience, the IPC commands, status, error codes, and the IPC_PARAM_BLOCK have been defined in the C include file PC-IPC.H. To use them, your application should contain the "include" directive for PC-IPC.H. Refer to your C compiler manual for the proper use of quotes, angle brackets, and pathnames. To avoid possible conflicts with other included files, all definitions begin with "IPC". One or more variables of the type IPC_PARAM_BLOCK should be defined in your application to provide an interface with IPC. An alternate method would be to allocate memory for each IPC_PARAM_BLOCK required. Of course, a pointer to the malloc'ed memory should be maintained by your application. Both methods are demonstrated in TX_PROC.C and RX_PROC.C. In either case, the IPC_PARAM_BLOCK must be passed to pc_ipc using a far pointer. Your application should determine whether IPC is currently installed prior to any attempts to use it. Unpredictable results will occur if the application assumes it is calling IPC when in fact some other TSR or driver (or nothing at all!) is using the vector. A call to pc_ipc_installed will return 1 (IPC_TRUE) if IPC is installed, or 0 (IPC_FALSE) if it is not. This facilitates the use of the boolean NOT (!) operator. A routine is provided to initialize an IPC_PARAM_BLOCK. Simply pass the values to be assigned and a far pointer to the parameter block. Typically, this routine is used just prior to a call to pc_ipc. Please note that even though a parameter may not be required for a particular command, you must supply all parameters to init_param_block. Unused parameters can be initialized to zero. Also note that 'data_ptr' is a far (32-bit) pointer. Therefore, when passing a null pointer (as in the case of IPC_CMND_DELID), it must be specified as "0L" (zero, long). If your C compiler does not support far pointers, you must devise a method of creating them in order to use IPC in your application. Some small data model C compilers provide variables that allow you to IPC User's Manual IPC 1.0 23 create a far pointer. For example, Toolworks C, version 3.2, provides variables that it uses in its startup module, CRT0.OBJ. The variables '_code' and '_data' contain the code segment and data segment register values. The following code fragment illustrates how to create a far pointer in a small data model program: extern unsigned int _data; unsigned long far_ptr; unsigned long segment; unsigned int offset; char my_data[128]; segment = (unsigned long)(_data) * 0x10; offset = &my_data; far_ptr = segment + offset; These demonstration applications exchange textual and integer data, but your application can send and retrieve any type of data. The only requirements IPC has are that a far pointer to the data and the size of the data be specified. For instance, if your application uses a video buffer, IPC could be the interface to allow "cut and paste" operations between processes. The application TX_PROC first verifies that IPC is installed at the default vector. It then checks to see if there is a message available for Process-0. If there is, it assumes that RX_PROC sent it and is waiting in another DESQview window. TX_PROC uses that message as 'to_id' for sending its message to RX_PROC. In other words, TX_PROC takes on the process id of RX_PROC. If no message is available for Process-0, TX_PROC assumes that it is not running in a DESQview window. It then obtains a second process id and sends it as a message to Process-0 for RX_PROC to find (take on) later. Whether DESQview is running or not, TX_PROC sends some data to the process id assigned to the variable 'proc_2_id'. Provided that no errors occur, the Send process terminates normally. The Receive process, RX_PROC, verifies that IPC is installed and checks for a message addressed to process id 0. If no message is available, RX_PROC assumes that it is running in a DESQview window and that TX_PROC has not run yet. It then allocates a process id (used later as 'my_id') and sends it to Process-0 for TX_PROC to find (take on) later. If a message is available for Process-0, RX_PROC assumes that TX_PROC has already run and that RX_PROC is not running in a DESQview window. RX_PROC uses the data as 'my_id' for requesting data. If RX_PROC assumes it is running in a DESQview window, it uses the IPC_CMND_RDATAW (wait for data) command. Otherwise, it makes an immediate request for a message. A successfully retrieved message is displayed on the standard output. IPC User's Manual IPC 1.0 24 Compiling and Linking IPCLIB.LIB was created using Turbo C (version 1.5) and was compiled using the Tiny memory model. But, as can be seen in the function prototypes declared in PC-IPC.H, the functions and pointers are all far-types. Turbo C recognizes the far-types in the function prototypes and automatically passes the correct parameter types regardless of the memory model used to compile and link your application. Refer to your C reference manual to determine if your compiler recognizes function prototypes and the extent of parameter checking in prototype declarations. IPCLIB.LIB is a "one size fits all" library in that it can be linked with objects compiled using any of the six memory models: tiny, small, medium, compact, large, and huge. In addition, IPCLIB.LIB does not reference any external functions and therefore does not require any run-time (external) libraries. This reduces the possibility of conflicts when linking and eliminates dependencies when executing. Below are two Turbo C examples of creating the executable file TX_PROC.EXE from the source file TX_PROC.C: Compile and Link in one command : TCC -ml -IC:\TURBOC\INCLUDE -LC:\TURBOC\LIB TX_PROC.C IPCLIB.LIB Compile TX_PROC.C using the large memory model. The include directory is c:\turboc\include. Link using the default libraries found in the directory c:\turboc\lib. Also use the library IPCLIB.LIB. Compile and Link in separate commands : TCC -ml -c -IC:\TURBOC\INCLUDE TX_PROC.C Compile TX_PROC.C using the large memory model. Compile to object file only. The include directory is c:\turboc\include. TLINK C:\TURBOC\LIB\C0L.OBJ TX_PROC.OBJ, TX_PROC.EXE, TX_PROC.MAP, IPCLIB.LIB C:\TURBOC\LIB\CL.LIB Link the large-model startup module C0L.OBJ, TX_PROC.OBJ, IPCLIB.LIB, and the large-model run-time library CL.LIB to produce TX_PROC.EXE and TX_PROC.MAP. IPC User's Manual IPC 1.0 25 Running TX_PROC and RX_PROC This section discusses how to run the two sample programs TX_PROC and RX_PROC. You should first run TX_PROC.EXE to store a message with IPC. You may specify the message to send by entering text on the command line. Otherwise, the default message "Howdy Doody and Buffalo Bob" is sent. The maximum amount of data that can be sent is 128 bytes. This is not a limitation of IPC or TX_PROC, but of DOS. Before you run either TX_PROC or RX_PROC, IPC must first be loaded. So if you type, A>tx_proc I read the news today, oh boy. TX_PROC should display the message you sent, what your process id was, and what process id the message was sent to. At this point, PC-IPC or RX_PROC may be used to retrieve the message. To use PC-IPC type: A>pc-ipc /i=1 /q 1 Messages Available. 972 Bytes Free Space.IPC is Installed, Enabled. A>pc-ipc /i=1 /r I read the news today, oh boy. To use RX_PROC you need only type "rx_proc" at the command line. As was said earlier, IPC can also work within multi-processing systems such as DESQview. Make certain IPC is installed before starting DESQview. Otherwise, IPC is hidden within a DESQview window. Start DESQview and open a "DOS (128K)" window. Change to the directory that has RX_PROC.EXE and run it. The program will appear to "hang" because there are no messages available. Open another "DOS (128K)" window and change to the directory that has TX_PROC.EXE. Resize both windows so you can observe both processes simultaneously. Run TX_PROC. The message you send appears in the first window and both RX_PROC and TX_PROC terminate normally. PC-IPC can also be used in either DESQview window to send or retrieve (or both) messages. You are encouraged to use RX_PROC.C and TX_PROC.C as templates for trying all the functions available in IPCLIB. IPC User's Manual IPC 1.0 26 Assembly Interface This section describes the use of IPC directly through Assembly routines. Two advantages of using an assembly interface to IPC (as with any program) are that program size is reduced and program speed is increased. A sample program is provided in the file IPCSAMP.ASM. IPCSAMP does not require IPCLIB, or any other externals, to use IPC. It demonstrates how to use IPC as you would any other Interrupt Service Routine (ISR). The structure of the parameter block passed to IPC is the same as used with IPCLIB (see 'IPC_PARAM_BLOCK struc' and 'param' in IPCSAMP.ASM). Required input fields are initialized, and output fields are returned, as they are with the C interface to IPCLIB. An example of determining whether IPC is installed is given in IPCSAMP. Older versions of DOS initialize unused interrupt vectors to 0000:0000. Your application should check for this prior to calling any ISR, since undesirable results (system crash) could occur. Later versions of DOS typically set unused vectors to point to an IRET (return from interrupt) instruction. Making a call to an IRET is harmless but unproductive. Therefore, once your application determines that the vector is not 0000:0000, it is safe to call the interrupt with an IPC_CMND_INQUIRE command. You must then check the 'status' field for IPC_STAT_INSTALLED and IPC_STAT_ENABLED. Since it is improbable (but not guaranteed) that another ISR would set these bits in this field, it is safe to assume that IPC is installed. In order to call IPC, the data segment and offset of the parameter block are pushed onto the stack. Then the call to the ISR is made with the "int vector_num" instruction. One disadvantage of using assembly is that the command IPC_CMND_RDATAW (wait for data) behaves exactly as IPC_CMND_RDATA does. In order to have your assembly routine wait for data, a loop that continually calls IPC is required. The following code fragment provides an example of how to do this: cmp param.command, RDATAW ; RDATAW EQU 010h jne normal_call ipc_loop: push ds mov ax, offset param.my_id push ax int IPC_VECTOR ; call IPC add sp, 4 ; clean up stack mov cx, param.status and cx, AVDATA_FLAG ; AVDATA_FLAG EQU 010h jz ipc_loop jmp process_data An example of assembling, linking, and running the Assembly interface program is provided in the block comment at the beginning of IPCSAMP.ASM. IPC User's Manual IPC 1.0 27 ERROR MESSAGES This section lists the error messages that can occur using PC-IPC, the return status values for PC-IPC, and the error codes that can occur using IPCLIB. PC-IPC Error Messages IPC is not installed. Run IPCINST.COM. PC-IPC was unable to find IPC at the specified vector. IPCINST.COM must be run prior to PC-IPC.COM. If IPC is installed, possibly the /V parameter specified in the PC-IPC command line does not match the /V parameter used to install IPC. Invalid or missing parameter : parameter Any command line syntax errors will produce this message. The parameter found to be in error will appear after the colon. Check for the proper use of the parameter in the "Using PC-IPC.COM" section. Unable to open "filename" for output. This message appears if PC-IPC is unable to open the file specified in the /R=filename and /W=filename commands. Check for proper use of filename specifications in the DOS User's Manual. Unable to add "envvar" to shell environment. PC-IPC was unable to add the environment variable to the environment table. The probable cause of this error is insufficient environment table space to contain the data returned to PC-IPC. See "PC-IPC Parameters" in the IPC User's Manual for further information on the environment table. Remember, if the /B parameter is used, PC-IPC constructs an environment variable of the form IPCvvi=data. IPC User's Manual IPC 1.0 28 PC-IPC Return Status PC-IPC returns the status of each operation in the DOS structure ERRORLEVEL (see the IF command in the DOS User's Manual). Using the IF ERRORLEVEL... construct allows your batch application to respond to the various conditions that can result using PC-IPC. Table 3 lists the errors and the corresponding ERRORLEVEL value returned by PC-IPC. Be aware that when testing ERRORLEVEL, the condition is true if ERRORLEVEL is equal to or greater than the value being tested. Example 3 in the "PC-IPC Examples" section illustrates the use of ERRORLEVEL in a batch file. ______________________________________________________________________ ERRORLEVEL Condition ---------- --------------------------------------- 0 Normal termination 1 Invalid command or parameter 2 Only Process 0 can install / reset IPC 3 That process cannot enable IPC 4 IPC is not enabled 5 That process cannot disable IPC 6 Invalid destination process id 7 Invalid sending process id 8 Invalid data destination 9 No more process ids available 10 Cannot relinquish that process id 11 Message space is full, no free memory 12 IPC is not installed Table 3 - Status Values Returned in ERRORLEVEL. All PC-IPC commands return the status of the requested operation in DOS's ERRORLEVEL. These status values correspond to those found in the "IPCLIB Error Messages" section. ______________________________________________________________________ IPC User's Manual IPC 1.0 29 IPCLIB Error Messages The following are error messages written to the standard output when ipc_error is called with a value returned from IPC. The define for the error appears in parentheses after the descriptive text. Invalid command. IPC does not recognize the command code specified in the "command" field of the IPC_PARAM_BLOCK. (IPC_ERR_BADCMND) Only process 0 can install / reset IPC. The "my_id" field of the IPC_PARAM_BLOCK must be 0 (zero) in order to perform an IPC_CMND_INSTALL. (IPC_ERR_INST0) Only the disabling process can re-enable. The "my_id" field contains a different process id for the IPC_CMND_ENABLE command than was specified for the IPC_CMND_DISABLE command. The ids must be identical. (IPC_ERR_CANTENAB) IPC is currently disabled. The command could not be processed because IPC is disabled. (IPC_ERR_NOTENAB) This process cannot disable IPC. IPC does not recognize the process id specified in the "my_id" field. Only registered process ids (those marked "in-use") may disable IPC. (IPC_ERR_CANTDISAB) The to-process id is not valid. The "to_id" field contains a process id that is not considered valid by IPC. Either a recognized id may be obtained from IPC using the IPC_CMND_REQID command, or use a number between 0 and 9. (IPC_ERR_BADTOID) The from-process id is not valid. The "my_id" field contains a process id that is not considered valid by IPC. Either a recognized id may be obtained from IPC using the IPC_CMND_REQID command, or use a number between 0 and 9. (IPC_ERR_BADFMID) Invalid target address for data. The far pointer specified in the "data_ptr" field is invalid (usually 0000:0000 if not initialized). (IPC_ERR_NOADDR) All available process ids are in use. IPC User's Manual IPC 1.0 30 All available process ids (0 through 9) are in use. A process id must be relinquished (IPC_CMND_DELID command) before another can be allocated. (IPC_ERR_MAXIDS) That process id cannot be relinquished. A request to relinquish a process id (IPC_CMND_DELID command) was made for a process id that is not currently in use. (IPC_ERR_CANTRELI) Insufficient memory available for message. IPC has run out of message space. Either request messages (IPC_CMND_RDATA, IPC_CMND_RDATAW commands) to free some message space, or increase the message space during installation with a larger value specified in the /A=nn parameter. (IPC_ERR_NOMEM) IPC is not installed. Run IPCINST.COM. IPC must be installed (memory resident) before it can be used. This error typically occurs when the /V=xx parameter specified during installation of IPC does not match the /V=xx parameter used by PC- IPC. IPC User's Manual IPC 1.0 31 PURCHASE INFORMATION This set of files is not part of the public domain. It is presented as a commercial product, and the right to use it must be purchased. This product may be freely copied and distributed, provided that the individual files remain as a set and that no part of this product is modified in any way. Any person, association, user group, institution, governing body, agency, or business that uses this product in whole or in part, is obligated to purchase the right to use it. Use of this product without compensation is theft. A large amount of work went into the development of the software, documentation, and examples in this product. Every effort has been made to insure accuracy, completeness, and that it performs as stated. Any malfunctions, inconsistencies, omissions, or errors are unintentional. Donnelly Software Engineering is not responsible for any loss due to the use or misuse of this product or its parts. Licensed users of this product are encouraged to contact Donnelly Software Engineering with comments or problems associated with its use. Donnelly Software Engineering may be contacted in writing at the address given below, by telephone at (714) 970-9612, or through CompuServe (user id 72647, 2543). Response to contacts from unlicensed users will be minimal. To become a licensed user of this product, complete the form below (or a reasonable facsimile) and sent it, along with a payment of $35.00 (US) for each license, to: DONNELLY SOFTWARE ENGINEERING 5082 WENDOVER RD. YORBA LINDA, CA 92686 Thank you for your patronage and support. IPC User's Manual IPC 1.0 32 ------------------------------------------------------------ DONNELLY SOFTWARE ENGINEERING 5082 WENDOVER RD. YORBA LINDA, CA 92686 (714) 970-9612 CompuServe 72647, 2543 LICENSE AGREEMENT I agree to purchase _____ license(s) to use the product known as IPC, at $35.00 per license, from Donnelly Software Engineering. I understand and agree to the following terms and conditions: 1) A single license entitles the licensee to use this product on a single computer. 2) Separate copies of this product, or its parts, each require a license. 3) Donnelly Software Engineering is not responsible for any loss incurred due to the use or misuse of this product. Thank you for your patronage and support. Name : _____________________________________________________ Institution, Position : ____________________________________ Address : __________________________________________________ City, State, Zip : _________________________________________ Signed : ___________________________________________________ ------------------------------------------------------------ IPC User's Manual IPC 1.0 33 ACKNOWLEDGMENTS MS-DOS is a trademark of Microsoft Corporation. DESQview is a trademark of Quarterdeck Office Systems. 8088, 80286, 80386 are trademarks of Intel Corporation. PC, XT, AT, MDA, CGA, EGA, VGA are trademarks of International Business Machines Corporation. Turbo C is a trademark of Borland International, Incorporated. CompuServe is a trademark of CompuServe Incorporated. Toolworks C is a trademark of The Software Toolworks. PC-IPC.COM, IPCINST.COM, IPCLIB.LIB, PC-IPC.H, PC-IPC.DOC and the IPC User's Manual are Copyrighted (c) 1989 Donnelly Software Engineering. INDEX /A parameter...........................3 /B parameter...........................7 /D command.............................6 /E command.............................6 /G command.............................7 /H command.............................6 /I parameter...........................8 /Q command.............................6 /R command.............................6 /S command.............................5 /V parameter, IPCINST..................3 /V parameter, PC-IPC...................8 /W command.............................6 allocate memory, parameter.............3 assembly..............................26 AUTOEXEC.BAT...........................2 batch mode, parameter..................7 C bindings............................21 commands, Communication................5 commands, Control......................6 commands, Information..................6 commands, IPC.........................16 commands, PC-IPC.......................5 commands, Routing......................7 CONFIG.SYS, environment size in........7 data, exchange with IPC...............14 default process id.....................8 default vector.........................8 DESQview, installing...................2 DESQview, running.....................25 disable, command.......................6 enable, command........................6 environment variables..................7 environment, size......................7 ERRORLEVEL, return value..............28 errors, IPCLIB........................29 errors, PC-IPC........................27 example, batch mode...................11 example, batch mode in DESQview.......12 example, command line..................9 FILLIPC.BAT...........................12 get id, command........................7 help, command..........................6 id, parameter..........................8 inquiry, command.......................6 installing IPC.........................2 instances, IPCINST.....................3 Interrupt Service Routine.............26 IPC data structure....................14 IPCINST.COM............................1 IPCLIB.LIB.............................1 IPC_PARAM_BLOCK.......................14 ISR...................................26 INDEX IVT, Interrupt Vector Table............3 main()................................22 memory models, supported..............24 memory, usage..........................3 MTIPC.BAT.............................12 multi-tasking..........................2 NULL terminated strings................5 overhead, message......................5 Parameters, PC-IPC.....................7 path, DOS..............................2 PC-IPC.COM.............................1 PC-IPC.DOC.............................1 PC-IPC.H...............................1 process ids............................7 process, DOS...........................8 recognized process id..................7 request data, command..................6 send data, command.....................5 setvar, use with /B....................7 status, IPC...........................19 status, returned by PC-IPC............28 TSR, Terminate-Stay-Resident...........1 usage, IPCINST.COM.....................3 usage, PC-IPC.COM......................5 valid process id.......................7 vector, IPCINST parameter..............3 vector, PC-IPC parameter...............8 vectors, available.....................3 wait for data, command.................6